home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / include / liveconnect / jsjava.h next >
C/C++ Source or Header  |  2006-05-08  |  15KB  |  314 lines
  1. /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
  2.  *
  3.  * ***** BEGIN LICENSE BLOCK *****
  4.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5.  *
  6.  * The contents of this file are subject to the Mozilla Public License Version
  7.  * 1.1 (the "License"); you may not use this file except in compliance with
  8.  * the License. You may obtain a copy of the License at
  9.  * http://www.mozilla.org/MPL/
  10.  *
  11.  * Software distributed under the License is distributed on an "AS IS" basis,
  12.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13.  * for the specific language governing rights and limitations under the
  14.  * License.
  15.  *
  16.  * The Original Code is Mozilla Communicator client code, released
  17.  * March 31, 1998.
  18.  *
  19.  * The Initial Developer of the Original Code is
  20.  * Netscape Communications Corporation.
  21.  * Portions created by the Initial Developer are Copyright (C) 1998
  22.  * the Initial Developer. All Rights Reserved.
  23.  *
  24.  * Contributor(s):
  25.  *
  26.  * Alternatively, the contents of this file may be used under the terms of
  27.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29.  * in which case the provisions of the GPL or the LGPL are applicable instead
  30.  * of those above. If you wish to allow use of your version of this file only
  31.  * under the terms of either the GPL or the LGPL, and not to allow others to
  32.  * use your version of this file under the terms of the MPL, indicate your
  33.  * decision by deleting the provisions above and replace them with the notice
  34.  * and other provisions required by the GPL or the LGPL. If you do not delete
  35.  * the provisions above, a recipient may use your version of this file under
  36.  * the terms of any one of the MPL, the GPL or the LGPL.
  37.  *
  38.  * ***** END LICENSE BLOCK ***** */
  39.  
  40. /*
  41.  * This file is part of the Java-vendor-neutral implementation of LiveConnect
  42.  *
  43.  * Publicly exported functions for JavaScript <==> Java communication.
  44.  *
  45.  */
  46.  
  47. #ifndef _JSJAVA_H
  48. #define _JSJAVA_H
  49.  
  50. #ifndef jstypes_h___
  51. #include "jstypes.h"
  52. #endif
  53.  
  54. JS_BEGIN_EXTERN_C
  55.  
  56. #include "jni.h"             /* Java Native Interface */
  57. #include "jsapi.h"           /* JavaScript engine API */
  58.  
  59. #if JS_BYTES_PER_LONG == 8
  60. typedef jlong lcjsobject;
  61. #else
  62. typedef jint lcjsobject;
  63. #endif
  64.  
  65. /*
  66.  * A JSJavaVM structure is a wrapper around a JavaVM which incorporates
  67.  * additional LiveConnect state.
  68.  */
  69. typedef struct JSJavaVM JSJavaVM;
  70.  
  71. /* LiveConnect and Java state, one per thread */
  72. typedef struct JSJavaThreadState JSJavaThreadState;
  73.  
  74. /*
  75.  * An opaque type that represents the connection to the Java VM. In stand-alone
  76.  * Java environments, this may be a JNI JavaVM object; in the browser environment
  77.  * it is a reference to a JVM plugin. A set of callbacks in the JSJCallbacks
  78.  * struct allow it to be manipulated.
  79.  */
  80. #ifdef OJI
  81. typedef struct SystemJavaVM SystemJavaVM;
  82. #else
  83. typedef JavaVM SystemJavaVM;
  84. #endif
  85.  
  86. /*
  87.  * This callback table provides hooks to external functions that implement
  88.  * functionality specific to the embedding.  For example, these callbacks are
  89.  * necessary in multi-threaded environments or to implement a security
  90.  * policy.
  91.  */
  92. typedef struct JSJCallbacks {
  93.  
  94.     /* This callback is invoked when there is no JavaScript execution
  95.        environment (JSContext) associated with the current Java thread and
  96.        a call is made from Java into JavaScript.  (A JSContext is associated
  97.        with a Java thread by calling the JSJ_SetDefaultJSContextForJavaThread()
  98.        function.)  This callback is only invoked when Java spontaneously calls
  99.        into JavaScript, i.e. it is not called when JS calls into Java which
  100.        calls back into JS.
  101.        
  102.        This callback can be used to create a JSContext lazily, or obtain
  103.        one from a pool of available JSContexts.  The implementation of this
  104.        callback can call JSJ_SetDefaultJSContextForJavaThread() to avoid any
  105.        further callbacks of this type for this Java thread. */
  106.     JSContext *         (*map_jsj_thread_to_js_context)(JSJavaThreadState *jsj_env,
  107. #ifdef OJI
  108.                                                         void *java_applet_obj,
  109. #endif
  110.                                                         JNIEnv *jEnv,
  111.                                                         char **errp);
  112.  
  113.     /* This callback is invoked whenever a call is made into Java from
  114.        JavaScript.  It's responsible for mapping from a JavaScript execution
  115.        environment (JSContext) to a Java thread.  (A JavaContext can only
  116.        be associated with one Java thread at a time.) */
  117.     JSJavaThreadState * (*map_js_context_to_jsj_thread)(JSContext *cx,
  118.                                                         char **errp);
  119.                                                         
  120.     /* This callback implements netscape.javascript.JSObject.getWindow(),
  121.        a method named for its behavior in the browser environment, where it
  122.        returns the JS "Window" object corresponding to the HTML window that an
  123.        applet is embedded within.  More generally, it's a way for Java to get
  124.        hold of a JS object that has not been explicitly passed to it. */
  125.     JSObject *          (*map_java_object_to_js_object)(JNIEnv *jEnv, void *pJavaObject,
  126.                                                         char **errp);
  127.         
  128.     /* An interim callback function until the LiveConnect security story is
  129.        straightened out.  This function pointer can be set to NULL. */
  130.     JSPrincipals *      (*get_JSPrincipals_from_java_caller)(JNIEnv *jEnv, JSContext *pJSContext, void **pNSIPrincipaArray, int numPrincipals, void *pNSISecurityContext);
  131.     
  132.     /* The following two callbacks sandwich any JS evaluation performed
  133.        from Java.   They may be used to implement concurrency constraints, e.g.
  134.        by suspending the current thread until some condition is met.  In the
  135.        browser embedding, these are used to maintain the run-to-completion
  136.        semantics of JavaScript.  It is acceptable for either function pointer
  137.        to be NULL. */
  138. #ifdef OJI
  139.     JSBool              (*enter_js_from_java)(JNIEnv *jEnv, char **errp,  void **pNSIPrincipaArray, int numPrincipals, void *pNSISecurityContext,void* applet_obj);
  140. #else
  141.     JSBool              (*enter_js_from_java)(JNIEnv *jEnv, char **errp);
  142. #endif
  143.     void                (*exit_js)(JNIEnv *jEnv, JSContext *cx);
  144.  
  145.     /* Most LiveConnect errors are signaled by calling JS_ReportError(), but in
  146.        some circumstances, the target JSContext for such errors is not
  147.        determinable, e.g. during initialization.  In such cases any error
  148.        messages are routed to this function.  If the function pointer is set to
  149.        NULL, error messages are sent to stderr. */
  150.     void                (*error_print)(const char *error_msg);
  151.  
  152.     /* This enables liveconnect to ask the VM for a java wrapper so that VM gets a chance to
  153.        store a mapping between a jsobject and java wrapper. So the unwrapping can be done on the
  154.        VM side before calling nsILiveconnect apis. This saves on a round trip request. */
  155.     jobject             (*get_java_wrapper)(JNIEnv *jEnv, lcjsobject jsobj);
  156.  
  157.     /* This allows liveconnect to unwrap a wrapped JSObject that is passed from java to js. 
  158.        This happens when Java code is passing back to JS an object that it got from JS. */
  159.     lcjsobject          (*unwrap_java_wrapper)(JNIEnv *jEnv, jobject java_wrapper);
  160.  
  161.     /* The following set of methods abstract over the JavaVM object. */
  162.     JSBool              (*create_java_vm)(SystemJavaVM* *jvm, JNIEnv* *initialEnv, void* initargs);
  163.     JSBool              (*destroy_java_vm)(SystemJavaVM* jvm, JNIEnv* initialEnv);
  164.     JNIEnv*             (*attach_current_thread)(SystemJavaVM* jvm);
  165.     JSBool              (*detach_current_thread)(SystemJavaVM* jvm, JNIEnv* env);
  166.     SystemJavaVM*       (*get_java_vm)(JNIEnv* env);
  167.  
  168.     /* Reserved for future use */
  169.     void *              reserved[10];
  170. } JSJCallbacks;
  171.  
  172. /*===========================================================================*/
  173.  
  174. /* A flag that denotes that a Java package has no sub-packages other than those
  175.    explicitly pre-defined at the time of initialization.  An access
  176.    to a simple name within such a package, therefore, must either correspond to
  177.    one of these explicitly pre-defined sub-packages or to a class within this
  178.    package.  It is reasonable for LiveConnect to signal an error if a simple
  179.    name does not comply with these criteria. */
  180. #define PKG_SYSTEM      1
  181.  
  182. /* A flag that denotes that a Java package which might contain sub-packages
  183.    that are not pre-defined at initialization time, because the sub-packages
  184.    may not be the same in all installations.  Therefore, an access to a simple
  185.    name within such a a package which does not correspond to either a
  186.    pre-defined sub-package or to a class, must be assummed to refer to an
  187.    unknown sub-package.  This behavior may cause bogus JavaPackage objects to be
  188.    created if a package name is misspelled, e.g. sun.oi.net. */
  189. #define PKG_USER        2
  190.  
  191. /* A Java package defined at initialization time. */
  192. typedef struct JavaPackageDef {
  193.     const char *        name;   /* e.g. "java.lang" */
  194.     const char *        path;   /* e.g. "java/lang", or NULL for default */
  195.     int                 flags;  /* PKG_USER, PKG_SYSTEM, etc. */
  196.     int                 access; /* JSPROP_READONLY or 0 */            
  197. } JavaPackageDef;
  198.  
  199. /*===========================================================================*/
  200.  
  201. /* The following two convenience functions present a complete, but simplified
  202.    LiveConnect API which is designed to handle the special case of a single 
  203.    Java-VM, with single-threaded operation, and the use of only one JSContext.
  204.    The full API is in the section below. */
  205.  
  206. /* Initialize the provided JSContext by setting up the JS classes necessary for
  207.    reflection and by defining JavaPackage objects for the default Java packages
  208.    as properties of global_obj.  If java_vm is NULL, a new Java VM is
  209.    created, using the provided classpath in addition to any default classpath.
  210.    The classpath argument is ignored, however, if java_vm is non-NULL. */
  211. JS_EXPORT_API(JSBool)
  212. JSJ_SimpleInit(JSContext *cx, JSObject *global_obj,
  213.                SystemJavaVM *java_vm, const char *classpath);
  214.  
  215. /* Free up all resources.  Destroy the Java VM if it was created by LiveConnect */
  216. JS_EXPORT_API(void)
  217. JSJ_SimpleShutdown(void);
  218.  
  219. /*===========================================================================*/
  220.  
  221. /* The "full" LiveConnect API, required when more than one thread, Java VM, or
  222.    JSContext is involved.  Initialization pseudocode might go roughly like
  223.    this:
  224.  
  225.    JSJ_Init()   // Setup callbacks
  226.    for each JavaVM {
  227.       JSJ_ConnectToJavaVM(...)
  228.    }
  229.    for each JSContext {
  230.       JSJ_InitJSContext(...)
  231.    }
  232.    for each JS evaluation {
  233.       run JavaScript code in the JSContext;
  234.    }
  235.  */
  236.  
  237. /* Called once for all instances of LiveConnect to set up callbacks */
  238. JS_EXPORT_API(void)
  239. JSJ_Init(JSJCallbacks *callbacks);
  240.  
  241. /* Called once per Java VM, this function initializes the classes, fields, and
  242.    methods required for Java reflection.  If java_vm is NULL, a new Java VM is
  243.    created according to the create_java_vm callback in the JSJCallbacks,
  244.    using the provided classpath in addition to any default initargs.
  245.    The initargs argument is ignored, however, if java_vm is non-NULL. */
  246. JS_EXPORT_API(JSJavaVM *)
  247. JSJ_ConnectToJavaVM(SystemJavaVM *java_vm, void* initargs);
  248.  
  249. /* Initialize the provided JSContext by setting up the JS classes necessary for
  250.    reflection and by defining JavaPackage objects for the default Java packages
  251.    as properties of global_obj.  Additional packages may be pre-defined by
  252.    setting the predefined_packages argument.  (Pre-defining a Java package at
  253.    initialization time is not necessary, but it will make package lookup faster
  254.    and, more importantly, will avoid unnecessary network accesses if classes
  255.    are being loaded over the network.) */
  256. JS_EXPORT_API(JSBool)
  257. JSJ_InitJSContext(JSContext *cx, JSObject *global_obj,
  258.                   JavaPackageDef *predefined_packages);
  259.    
  260. /* This function returns a structure that encapsulates the Java and JavaScript
  261.    execution environment for the current native thread.  It is intended to
  262.    be called from the embedder's implementation of JSJCallback's
  263.    map_js_context_to_jsj_thread() function.  The thread_name argument is only
  264.    used for debugging purposes and can be set to NULL.  The Java JNI
  265.    environment associated with this thread is returned through the java_envp
  266.    argument if java_envp is non-NULL.  */
  267. JS_EXPORT_API(JSJavaThreadState *)
  268. JSJ_AttachCurrentThreadToJava(JSJavaVM *jsjava_vm, const char *thread_name,
  269.                               JNIEnv **java_envp);
  270.  
  271. /* Destructor routine for per-thread JSJavaThreadState structure */
  272. JS_EXPORT_API(JSBool)
  273. JSJ_DetachCurrentThreadFromJava(JSJavaThreadState *jsj_env);
  274.  
  275. /* This function is used to specify a particular JSContext as *the* JavaScript
  276.    execution environment to be used when LiveConnect is accessed from the given
  277.    Java thread, i.e. when one of the methods of netscape.javascript.JSObject
  278.    has been called.  There can only be one such JS context for any given Java
  279.    thread at a time.  (To multiplex JSContexts among a single thread, this
  280.    function could be called before Java is invoked on that thread.)  The return
  281.    value is the previous JSContext associated with the given Java thread.
  282.  
  283.    If this function has not been called for a thread and a crossing is made
  284.    into JavaScript from Java, the map_jsj_thread_to_js_context() callback will
  285.    be invoked to determine the JSContext for the thread.  The purpose of the 
  286.    function is to improve performance by avoiding the expense of the callback.
  287. */
  288. JS_EXPORT_API(JSContext *)
  289. JSJ_SetDefaultJSContextForJavaThread(JSContext *cx, JSJavaThreadState *jsj_env);
  290.  
  291. /* This routine severs the connection to a Java VM, freeing all related resources.
  292.    It shouldn't be called until the global scope has been cleared in all related
  293.    JSContexts (so that all LiveConnect objects are finalized) and a JavaScript
  294.    GC is performed.  Otherwise, accessed to free'ed memory could result. */
  295. JS_EXPORT_API(void)
  296. JSJ_DisconnectFromJavaVM(JSJavaVM *);
  297.  
  298. /*
  299.  * Reflect a Java object into a JS value.  The source object, java_obj, must
  300.  * be of type java.lang.Object or a subclass and may, therefore, be an array.
  301.  */
  302. JS_EXPORT_API(JSBool)
  303. JSJ_ConvertJavaObjectToJSValue(JSContext *cx, jobject java_obj, jsval *vp);
  304.  
  305. JS_EXPORT_API(JSBool)
  306. JSJ_ConvertJSValueToJavaObject(JSContext *cx, jsval js_val, jobject *vp);
  307.  
  308. JS_EXPORT_API(JSBool)
  309. JSJ_IsJSCallApplet();
  310.  
  311. JS_END_EXTERN_C
  312.  
  313. #endif  /* _JSJAVA_H */
  314.